<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
  "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
  <head>
    <meta name="Content-Type" content="text/html; charset=utf-8" />
<title>Documentation by YARD 0.6.3</title>
<link rel="stylesheet" href="css/style.css" type="text/css" media="screen" charset="utf-8" />
<link rel="stylesheet" href="css/common.css" type="text/css" media="screen" charset="utf-8" />

<script type="text/javascript" charset="utf-8">
  relpath = '';
  if (relpath != '') relpath += '/';
</script>
<script type="text/javascript" charset="utf-8" src="js/jquery.js"></script>
<script type="text/javascript" charset="utf-8" src="js/app.js"></script>

  </head>
  <body>
    <script type="text/javascript" charset="utf-8">
      if (window.top.frames.main) document.body.className = 'frames';
    </script>
    
    <div id="header">
      <div id="menu">
  
    <a href="_index.html" title="Index">Index</a> &raquo; 
    <span class="title">File: README</span>
  
  
  <div class="noframes"><span class="title">(</span><a href="." target="_top">no frames</a><span class="title">)</span></div>
</div>

      <div id="search">
  <a id="class_list_link" href="#">Class List</a>
  <a id="method_list_link" href="#">Method List</a>
  <a id ="file_list_link" href="#">File List</a>
</div>

      <div class="clear"></div>
    </div>
    
    <iframe id="search_frame"></iframe>
    
    <div id="content"><div id='filecontents'><h1>Ruby Ensembl Core API tutorial</h1>
<p>
By Jan Aerts. Copy-paste-modified from the excellent perl API tutorial at
http://www.ensembl.org/info/software/core/core_tutorial.html (with
permission of the core Ensembl team).
</p>
<p>
Based on release 60.
</p>
<h2>Introduction</h2>
<p>
This tutorial describes how to use the Ensembl Core Ruby API. It is
intended to be an introduction and demonstration of the general API
concepts. This tutorial is not comprehensive, but it will hopefully enable
to reader to become quickly productive, and facilitate a rapid
understanding of the core system. This tutorial assumes at least some
familiarity with Ruby.
</p>
<p>
The Ruby API provides a level of abstraction over the Ensembl Core
databases. To external users the API may be useful to automate the
extraction of particular data. As a brief introduction this tutorial
focuses primarily on the retrieval of data from the Ensembl Core databases.
</p>
<p>
The Ruby API is only one of many ways of accessing the data stored in
Ensembl. Additionally there is a genome browser web interface, and the
BioMart system. BioMart may be a more appropriate tool for certain types of
data mining.
</p>
<p>
This API is for read-only querying of the database.
</p>
<h2>Other sources of information</h2>
<p>
The Ensembl Core API has a decent set of code documentation in the form of
standard Ruby RDOC. This is documentation is mixed in with the actual code,
but can be automatically extracted and formatted using some software tools.
One version of this documentation is available at the website you&#8217;re
looking at.
</p>
<p>
If you have your RUBYLIB environment variable set correctly, you can use
the command ri. For example the following command will bring up some
documentation about the Slice class and each of its methods:
</p>
<pre class="code">
  <span class='ri identifier id'>ri</span> <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='Slice constant id'>Slice</span>
</pre>
<p>
For additional information you can contact Jan Aerts
(jan.aerts@sanger.ac.uk) or preferably send an email to the bioruby mailing
list (see http://www.bioruby.org).
</p>
<h2>Obtaining and installing the code</h2>
<p>
The Ensembl Ruby API is made available as a gem. See the github site for
more information (http://github.com/jandot/ruby-ensembl-api/wikis/home).
</p>
<p>
Basically, it comes down to:
</p>
<pre class="code">
  <span class='sudo identifier id'>sudo</span> <span class='gem identifier id'>gem</span> <span class='install identifier id'>install</span> <span class='jandot identifier id'>jandot</span><span class='minus op'>-</span><span class='ruby identifier id'>ruby</span><span class='minus op'>-</span><span class='ensembl identifier id'>ensembl</span><span class='minus op'>-</span><span class='api identifier id'>api</span> <span class='minus op'>-</span><span class='minus op'>-</span><span class='source identifier id'>source</span> <span class='http identifier id'>http</span><span class='symbol val'>:/</span><span class='regexp val'>/gems.github.com
</span></pre>
<h2>Code conventions</h2>
<p>
Several naming conventions are used throughout the API. Learning these
conventions will aid in your understanding of the code.
</p>
<p>
Variable names are underscore-separated all lower-case words.
</p>
<pre class="code">
  <span class='slice_1 identifier id'>slice_1</span>
  <span class='exon_1 identifier id'>exon_1</span>
  <span class='gene_a identifier id'>gene_a</span>
</pre>
<p>
Class and package names are CamelCase words that begin with capital
letters.
</p>
<pre class="code">
  <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='Gene constant id'>Gene</span>
  <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='Exon constant id'>Exon</span>
  <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='CoordSystem constant id'>CoordSystem</span>
  <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='SeqRegion constant id'>SeqRegion</span>
</pre>
<p>
Method names are entirely lower-case, underscore separated words. Methods
are called on an object or class by appending a period to that object or
class and adding the method name.
</p>
<pre class="code">
  <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='genes identifier id'>genes</span>
  <span class='transcript_a identifier id'>transcript_a</span><span class='dot token'>.</span><span class='five_prime_utr_seq identifier id'>five_prime_utr_seq</span>
</pre>
<p>
Class methods are responsible for the creation of various objects. Most of
this is standard ActiveRecord behaviour and will be discussed below.
</p>
<h2>ActiveRecord</h2>
<p>
Most of the API is based on ActiveRecord to get data from that database. In
general, each table is described by a class with the same name: the
coord_system table is covered by the Ensembl::Core::CoordSystem class, the
seq_region table is covered by the Ensembl::Core::SeqRegion class, etc. As
a result, accessors are available for all columns in each table. For
example, the seq_region table has the following columns: seq_region_id,
name, coord_system_id and length. Through ActiveRecord, these column names
become available as attributes of Ensembl::Core::SeqRegion objects:
</p>
<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='my_seq_region identifier id'>my_seq_region</span><span class='dot token'>.</span><span class='seq_region_id identifier id'>seq_region_id</span>
  <span class='puts identifier id'>puts</span> <span class='my_seq_region identifier id'>my_seq_region</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
  <span class='puts identifier id'>puts</span> <span class='my_seq_region identifier id'>my_seq_region</span><span class='dot token'>.</span><span class='coord_system_id identifier id'>coord_system_id</span>
  <span class='puts identifier id'>puts</span> <span class='my_seq_region identifier id'>my_seq_region</span><span class='dot token'>.</span><span class='length identifier id'>length</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
</pre>
<p>
ActiveRecord makes it easy to extract data from those tables using the
collection of find methods. There are three types of find methods (e.g. for
the Ensembl::Core::CoordSystem class):
</p>
<ul>
<li>find based on primary key in table:

<pre class="code">
  <span class='my_coord_system identifier id'>my_coord_system</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find identifier id'>find</span><span class='lparen token'>(</span><span class='integer val'>5</span><span class='rparen token'>)</span>
</pre>
</li>
<li>find_by_sql:

<pre class="code">
  <span class='my_coord_system identifier id'>my_coord_system</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find_by_sql identifier id'>find_by_sql</span><span class='lparen token'>(</span><span class='string val'>'SELECT * FROM coord_system WHERE name = '</span><span class='chromosome identifier id'>chromosome</span><span class='string val'>'&quot;)
</span></pre>
</li>
<li>find_by_&lt;insert_your_column_name_here&gt;

<pre class="code">
  <span class='my_coord_system1 identifier id'>my_coord_system1</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='rparen token'>)</span>
  <span class='my_coord_system2 identifier id'>my_coord_system2</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find_by_rank identifier id'>find_by_rank</span><span class='lparen token'>(</span><span class='integer val'>3</span><span class='rparen token'>)</span>
</pre>
</li>
</ul>
<p>
To find out which find_by_&lt;column&gt; methods are available, you can
list the column names using the column_names class methods:
</p>
<pre class="code">
 <span class='puts identifier id'>puts</span> <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='column_names identifier id'>column_names</span><span class='dot token'>.</span><span class='join identifier id'>join</span><span class='lparen token'>(</span><span class='string val'>&quot;\t&quot;</span><span class='rparen token'>)</span>
</pre>
<p>
For more information on the find methods, see
ar.rubyonrails.org/classes/ActiveRecord/Base.html#M000344
</p>
<p>
The relationships between different tables are accessible through the
classes as well. For example, to loop over all seq_regions belonging to a
coord_system (a coord_system &quot;has many&quot; seq_regions):
</p>
<pre class="code">
  <span class='chr_coord_system identifier id'>chr_coord_system</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='rparen token'>)</span>
  <span class='chr_coord_system identifier id'>chr_coord_system</span><span class='dot token'>.</span><span class='seq_regions identifier id'>seq_regions</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='seq_region identifier id'>seq_region</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='seq_region identifier id'>seq_region</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
  <span class='end end kw'>end</span>
</pre>
<p>
Of course, you can go the other way as well (a seq_region &quot;belongs
to&quot; a coord_system):
</p>
<pre class="code">
  <span class='chr4 identifier id'>chr4</span> <span class='assign token'>=</span> <span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'4'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='chr4 identifier id'>chr4</span><span class='dot token'>.</span><span class='coord_system identifier id'>coord_system</span><span class='dot token'>.</span><span class='name identifier id'>name</span>  <span class='comment val'>#--&gt; 'chromosome'</span>
</pre>
<p>
To find out what relationships exist for a given class, you can use the
reflect_on_all_associations class methods:
</p>
<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='reflect_on_all_associations identifier id'>reflect_on_all_associations</span><span class='lparen token'>(</span><span class='symbol val'>:has_many</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='collect identifier id'>collect</span><span class='lbrace token'>{</span><span class='bitor op'>|</span><span class='a identifier id'>a</span><span class='bitor op'>|</span> <span class='a identifier id'>a</span><span class='dot token'>.</span><span class='name identifier id'>name</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span><span class='rbrace token'>}</span><span class='dot token'>.</span><span class='join identifier id'>join</span><span class='lparen token'>(</span><span class='string val'>&quot;\n&quot;</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='reflect_on_all_associations identifier id'>reflect_on_all_associations</span><span class='lparen token'>(</span><span class='symbol val'>:has_one</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='collect identifier id'>collect</span><span class='lbrace token'>{</span><span class='bitor op'>|</span><span class='a identifier id'>a</span><span class='bitor op'>|</span> <span class='a identifier id'>a</span><span class='dot token'>.</span><span class='name identifier id'>name</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span><span class='rbrace token'>}</span><span class='dot token'>.</span><span class='join identifier id'>join</span><span class='lparen token'>(</span><span class='string val'>&quot;\n&quot;</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='reflect_on_all_associations identifier id'>reflect_on_all_associations</span><span class='lparen token'>(</span><span class='symbol val'>:belongs_to</span><span class='rparen token'>)</span><span class='dot token'>.</span><span class='collect identifier id'>collect</span><span class='lbrace token'>{</span><span class='bitor op'>|</span><span class='a identifier id'>a</span><span class='bitor op'>|</span> <span class='a identifier id'>a</span><span class='dot token'>.</span><span class='name identifier id'>name</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span><span class='rbrace token'>}</span><span class='dot token'>.</span><span class='join identifier id'>join</span><span class='lparen token'>(</span><span class='string val'>&quot;\n&quot;</span><span class='rparen token'>)</span>
</pre>
<h2>Connecting to the Ensembl database and a minimal script</h2>
<p>
All data used and created by Ensembl is stored in MySQL relational
databases. If you want to access this database the first thing you have to
do is to connect to it. This is done behind the scenes using the
ActiveRecord module.
</p>
<p>
First, we need to tell our computer where they can find the API code. This
information is contained in the RUBYLIB environment variable. Suppose you
have save the API in /usr/local/lib/ruby/ensembl-api (with subdirectories
lib/, test/, samples/, &#8230;), you could set the environment variable on
a bash shell like this:
</p>
<pre class="code">
  <span class='export identifier id'>export</span> <span class='RUBYLIB constant id'>RUBYLIB</span><span class='assign token'>=</span><span class='$RUBYLIB gvar id'>$RUBYLIB</span><span class='symbol val'>:/</span><span class='usr identifier id'>usr</span><span class='div op'>/</span><span class='local identifier id'>local</span><span class='div op'>/</span><span class='lib identifier id'>lib</span><span class='div op'>/</span><span class='ruby identifier id'>ruby</span><span class='div op'>/</span><span class='ensembl identifier id'>ensembl</span><span class='minus op'>-</span><span class='api identifier id'>api</span><span class='div op'>/</span><span class='lib identifier id'>lib</span>
</pre>
<p>
Next, we need to import all Ruby modules that we will be using. Every
Ensembl script that you will write will contain a use statement like the
following:
</p>
<pre class="code">
  <span class='require identifier id'>require</span> <span class='string val'>'ensembl'</span>
</pre>
<p>
Alternatively, if you installed the API as a gem, you would write:
</p>
<pre class="code">
  <span class='require identifier id'>require</span> <span class='string val'>'rubygems'</span>
  <span class='require_gem identifier id'>require_gem</span> <span class='string val'>'ensembl-api'</span>
</pre>
<p>
Ensembl stores its data in a separate database for each species and each
release of that species. The Ruby Ensembl API does a lot automatically, so
you only have to know the species name to connect to the release 45 version
of its core database. This name should be provided in snake_case (all
lowercase connected by underscore):
</p>
<pre class="code">
  <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='CoreDBConnection constant id'>CoreDBConnection</span><span class='dot token'>.</span><span class='connect identifier id'>connect</span><span class='lparen token'>(</span><span class='string val'>'homo_sapiens'</span><span class='rparen token'>)</span>
</pre>
<p>
With the connection established, you&#8217;ll be able to get objects from
the database, e.g.
</p>
<pre class="code">
  <span class='chromosome_4 identifier id'>chromosome_4</span> <span class='assign token'>=</span> <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span><span class='colon2 op'>::</span><span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'4'</span><span class='rparen token'>)</span>
</pre>
<p>
You have to include the &#8216;Ensembl::Core::&#8217; bit to every call to
a class. However, if you include the line
</p>
<pre class="code">
  <span class='include identifier id'>include</span> <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span>
</pre>
<p>
just after you &quot;require &#8216;ensembl&#8217;&quot;, you don&#8217;t
have to anymore. The rest of this tutorial expects you to have done the
include command. So a very short but complete ruby script could look like
this:
</p>
<pre class="code">
  <span class='require identifier id'>require</span> <span class='string val'>'ensembl'</span>
  <span class='include identifier id'>include</span> <span class='Ensembl constant id'>Ensembl</span><span class='colon2 op'>::</span><span class='Core constant id'>Core</span>
  <span class='CoreDBConnection constant id'>CoreDBConnection</span><span class='dot token'>.</span><span class='connect identifier id'>connect</span><span class='lparen token'>(</span><span class='string val'>'homo_sapiens'</span><span class='rparen token'>)</span>
  <span class='chromosome_4 identifier id'>chromosome_4</span> <span class='assign token'>=</span> <span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'4'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='chromosome_4 identifier id'>chromosome_4</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
</pre>
<h2>Slices</h2>
<p>
A Slice object represents a single continuous region of a genome. Slices
can be used to obtain sequence, features or other information from a
particular region of interest. There are several ways to obtain a slice,
but we will start with the Ensembl::Core::Slice#fetch_by_region method
which is the most commonly used. This class method takes numerous arguments
but most of them are optional. In order, the arguments are:
coord_system_name, seq_region_name, start, end, strand,
coord_system_version. The following are several examples of how to use the
Ensembl::Core::Slice#fetch_by_region method:
</p>
<ul>
<li>Obtain a slice covering the entire chromosome X

<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span> <span class='string val'>'X'</span><span class='rparen token'>)</span>
</pre>
</li>
<li>Obtain a slice covering the entire clone AL359765.6

<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'clone'</span><span class='comma token'>,</span> <span class='string val'>'AL359765.6'</span><span class='rparen token'>)</span>
</pre>
</li>
<li>Obtain a slice covering an entire NT contig

<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'supercontig'</span><span class='comma token'>,</span> <span class='string val'>'NT_011333'</span><span class='rparen token'>)</span>
</pre>
</li>
<li>Obtain a slice covering the region from 1MB to 2MB (inclusively) of
chromosome 20

<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span> <span class='string val'>'20'</span><span class='comma token'>,</span> <span class='integer val'>1000000</span><span class='comma token'>,</span> <span class='integer val'>2000000</span><span class='rparen token'>)</span>
</pre>
</li>
</ul>
<p>
Another useful way to obtain a slice is with respect to a gene, e.g. with
5kb flanking sequence:
</p>
<pre class="code">
    <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_gene_stable_id identifier id'>fetch_by_gene_stable_id</span><span class='lparen token'>(</span><span class='string val'>'ENSG00000099889'</span><span class='comma token'>,</span> <span class='integer val'>5000</span><span class='rparen token'>)</span>
</pre>
<p>
This will return a slice that contains the sequence of the gene specified
by its stable Ensembl ID. It also returns 5000bp of flanking sequence at
both the 5&#8217; and 3&#8217; ends, which is useful if you are interested
in the environs that a gene inhabits. You needn&#8217;t have the flanking
sequence it you don&#8217;t want it &#8212; in this case set the number of
flanking bases to zero or simply omit the second argument entirely. Note
that the fetch_by_gene_stable_id() method always returns a slice on the
forward strand even if the gene is on the reverse strand.
</p>
<p>
To retrieve a set of slices from a particular coordinate system the
fetch_all method can be used:
</p>
<ul>
<li>Retrieve slices of every chromosome in the database

<pre class="code">
  <span class='slices identifier id'>slices</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_all identifier id'>fetch_all</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='rparen token'>)</span>
</pre>
</li>
<li>Retrieve slices of every BAC clone in the database

<pre class="code">
  <span class='slices identifier id'>slices</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_all identifier id'>fetch_all</span><span class='lparen token'>(</span><span class='string val'>'clone'</span><span class='rparen token'>)</span>
</pre>
</li>
</ul>
<p>
For certain types of analysis it is necessary to break up regions into
smaller manageable pieces. The method Slice#split can be used to break up
larger slices into smaller component slices. The following code creates an
array of subslices of chromosome 1, with the (maximal) length of each slice
100000 bp and an overlap of 250 bp.
</p>
<pre class="code">
  <span class='big_slice identifier id'>big_slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span> <span class='integer val'>1</span><span class='rparen token'>)</span>
  <span class='subslices identifier id'>subslices</span> <span class='assign token'>=</span> <span class='big_slice identifier id'>big_slice</span><span class='dot token'>.</span><span class='split identifier id'>split</span><span class='lparen token'>(</span><span class='integer val'>100000</span><span class='comma token'>,</span> <span class='integer val'>250</span><span class='rparen token'>)</span>
</pre>
<p>
To obtain sequence from a slice the Slice#seq method can be used:
</p>
<pre class="code">
  <span class='seq identifier id'>seq</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='seq identifier id'>seq</span>
  <span class='puts identifier id'>puts</span> <span class='seq identifier id'>seq</span>
</pre>
<p>
We can query the slice for information about itself:
</p>
<pre class="code">
  <span class='seq_region identifier id'>seq_region</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='seq_region identifier id'>seq_region</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
  <span class='coord_system identifier id'>coord_system</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='seq_region identifier id'>seq_region</span><span class='dot token'>.</span><span class='coord_system identifier id'>coord_system</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
  <span class='start identifier id'>start</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='start identifier id'>start</span>
  <span class='stop identifier id'>stop</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='stop identifier id'>stop</span>
  <span class='strand identifier id'>strand</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='strand identifier id'>strand</span>

  <span class='puts identifier id'>puts</span> <span class='dstring node'>&quot;Slice: #{coord_system} #{seq_region} #{start}-#{stop} (#{strand})&quot;</span>
</pre>
<p>
Many classes can provide a set of features which overlap a slice. The slice
itself also provides a means to obtain features which overlap its region.
To obtain a list of genes which overlap a slice:
</p>
<pre class="code">
  <span class='slice_a identifier id'>slice_a</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span><span class='string val'>'X'</span><span class='rparen token'>)</span>
  <span class='genes identifier id'>genes</span> <span class='assign token'>=</span> <span class='slice_a identifier id'>slice_a</span><span class='dot token'>.</span><span class='genes identifier id'>genes</span>
</pre>
<p>
<b>CAUTION</b>: The slice concept is a little bit different from that in
the perl API. If you ask a gene for its slice using the perl API, you get a
slice covering the <em>whole</em> of the chromosome. In contrast, the slice
created by the ruby API only contains that bit covered by the gene. The
Ensembl::Core::SeqRegion class is used to refer to whole things. I just
found it much more intuitive like that&#8230;
</p>
<h2>Features</h2>
<p>
Features are objects in the database which have a defined location on the
genome. All features in Ensembl include the Ensembl::Core::Sliceable mixin
and have the following location defining attributes: start, end, strand,
slice.
</p>
<p>
All feature objects can be retrieved using their #find method of their
class or any of the generic #find_by_() methods (see the ActiveRecord bit
of this tutorial). The following example illustrates how Transcript
features and DnaDnaAlignFeature features can be obtained from the database.
All features in the database can be retrieved in similar ways from their
own object adaptors.
</p>
<ul>
<li>Get a slice of chromosome 20, 10MB-11MB

<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span> <span class='string val'>'20'</span><span class='comma token'>,</span> <span class='integer val'>10000000</span><span class='comma token'>,</span> <span class='integer val'>11000000</span> <span class='rparen token'>)</span>
</pre>
</li>
<li>Fetch all of the transcripts overlapping chromosome 20, 10MB-11MB

<pre class="code">
  <span class='transcripts identifier id'>transcripts</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='transcripts identifier id'>transcripts</span>
  <span class='transcripts identifier id'>transcripts</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='transcript identifier id'>transcript</span><span class='bitor op'>|</span>
    <span class='name identifier id'>name</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>
    <span class='internal_id identifier id'>internal_id</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='id identifier id'>id</span>
    <span class='start identifier id'>start</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='start identifier id'>start</span>
    <span class='stop identifier id'>stop</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='stop identifier id'>stop</span>
    <span class='strand identifier id'>strand</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='strand identifier id'>strand</span>

    <span class='puts identifier id'>puts</span> <span class='dstring node'>&quot;Transcript #{name} [#{internal_id}] #{start}-#{stop} (#{strand})&quot;</span>
  <span class='end end kw'>end</span>
</pre>
</li>
<li>Fetch all of the DNA-DNA alignments overlapping chromosome 20, 10MB-11MB

<pre class="code">
  <span class='dafs identifier id'>dafs</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='dna_align_features identifier id'>dna_align_features</span>
  <span class='dafs identifier id'>dafs</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='daf identifier id'>daf</span><span class='bitor op'>|</span>
    <span class='name identifier id'>name</span> <span class='assign token'>=</span> <span class='daf identifier id'>daf</span><span class='dot token'>.</span><span class='hit_name identifier id'>hit_name</span>
    <span class='internal_id identifier id'>internal_id</span> <span class='assign token'>=</span> <span class='daf identifier id'>daf</span><span class='dot token'>.</span><span class='id identifier id'>id</span>
    <span class='start identifier id'>start</span> <span class='assign token'>=</span> <span class='daf identifier id'>daf</span><span class='dot token'>.</span><span class='start identifier id'>start</span>
    <span class='stop identifier id'>stop</span> <span class='assign token'>=</span> <span class='daf identifier id'>daf</span><span class='dot token'>.</span><span class='stop identifier id'>stop</span>
    <span class='strand identifier id'>strand</span> <span class='assign token'>=</span> <span class='daf identifier id'>daf</span><span class='dot token'>.</span><span class='strand identifier id'>strand</span>

    <span class='puts identifier id'>puts</span> <span class='dstring node'>&quot;DNA alignment #{name} [#{internal_id}] #{start}-#{stop} (#{strand})&quot;</span>
  <span class='end end kw'>end</span>
</pre>
</li>
<li>Fetch a transcript by its internal identifier

<pre class="code">
  <span class='transcript identifier id'>transcript</span> <span class='assign token'>=</span> <span class='Transcript constant id'>Transcript</span><span class='dot token'>.</span><span class='find identifier id'>find</span><span class='lparen token'>(</span><span class='integer val'>100</span><span class='rparen token'>)</span>
</pre>
</li>
<li>Fetch a DnaAlignFeature by its internal identifiers

<pre class="code">
  <span class='daf identifier id'>daf</span> <span class='assign token'>=</span> <span class='DnaAlignFeature constant id'>DnaAlignFeature</span><span class='dot token'>.</span><span class='find identifier id'>find</span><span class='lparen token'>(</span><span class='integer val'>100</span><span class='rparen token'>)</span>
</pre>
</li>
</ul>
<p>
All features also have the transform method which are described in detail
in a later section of this tutorial.
</p>
<h3>Features across coordinate systems</h3>
<p>
In the Ensembl database, some features might be related to one coordinate
system, while other features are related to another one (for more
information on coordinate systems, see below). For example, there are three
coordinate systems in cow: contigs, scaffolds and chromosomes. Scaffold
Chr4.003.122 does not have any simple_features on it. However, the
equivalent regions in the contig and chromosome coordinate systems have 37
and 85 (=total of 122), respectively. If you therefore ask that scaffold to
list its simple_features, you wouldn&#8217;t get any. A workaround for
this, is to first create a slice for this scaffold, and ask that
<em>slice</em> for its simple_features.
</p>
<pre class="code">
  <span class='scaffold identifier id'>scaffold</span> <span class='assign token'>=</span> <span class='SeqRegion constant id'>SeqRegion</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'Chr4.003.122'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='scaffold identifier id'>scaffold</span><span class='dot token'>.</span><span class='simple_features identifier id'>simple_features</span><span class='dot token'>.</span><span class='length identifier id'>length</span> <span class='comment val'>#--&gt; 0</span>
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'scaffold'</span><span class='comma token'>,</span><span class='string val'>'Chr4.003.122'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='simple_features identifier id'>simple_features</span><span class='dot token'>.</span><span class='length identifier id'>length</span>    <span class='comment val'>#--&gt; 122</span>
</pre>
<p>
or even:
</p>
<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='scaffold identifier id'>scaffold</span><span class='dot token'>.</span><span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='simple_features identifier id'>simple_features</span><span class='dot token'>.</span><span class='length identifier id'>length</span> <span class='comment val'>#--&gt; 122</span>
</pre>
<p>
The reason this works, is that any retrieval for a slice also checks what
coordinate systems that type of feature is annotated on.
</p>
<h2>Genes, Transcripts, and Exons</h2>
<p>
Genes, exons and transcripts are also features and can be treated in the
same way as any other feature within Ensembl. A transcript in Ensembl is a
grouping of exons. A gene in Ensembl is a grouping of transcripts which
share any overlapping (or partially overlapping) exons. Transcripts also
have an associated Translation object which defines the UTR and CDS
composition of the transcript. Introns are not defined explicitly in the
database but can be obtained by the Ensembl::Core::Transcript#introns
method (not implemented yet).
</p>
<p>
Important: like all Ensembl features the start of an exon is always less
than or equal to the end of the exon, regardless of the strand it is on.
The start of the transcript is the start of the first exon of a transcript
on the forward strand or the start of the last exon of a transcript on the
reverse strand. The start and end of a gene are defined to be the lowest
start value of its transcripts and the highest end value respectively.
</p>
<p>
Genes, translations, transcripts and exons all have stable identifiers.
These are identifiers that are assigned to Ensembl&#8217;s predictions, and
maintained in subsequent releases. For example, if a transcript (or a
sufficiently similar transcript) is re-predicted in a future release then
it will be assigned the same stable identifier as its predecessor.
</p>
<p>
The following is an example of the retrieval of a set of genes, transcripts
and exons:
</p>
<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span><span class='string val'>'X'</span><span class='comma token'>,</span><span class='integer val'>1000000</span><span class='comma token'>,</span><span class='integer val'>10000000</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='display_name identifier id'>display_name</span>

  <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='genes identifier id'>genes</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='gene identifier id'>gene</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='string val'>&quot;\t&quot;</span> <span class='plus op'>+</span> <span class='gene identifier id'>gene</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>

    <span class='gene identifier id'>gene</span><span class='dot token'>.</span><span class='transcripts identifier id'>transcripts</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='transcript identifier id'>transcript</span><span class='bitor op'>|</span>
      <span class='puts identifier id'>puts</span> <span class='string val'>&quot;\t\t&quot;</span> <span class='plus op'>+</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>

      <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='exons identifier id'>exons</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='exon identifier id'>exon</span><span class='bitor op'>|</span>
        <span class='puts identifier id'>puts</span> <span class='string val'>&quot;\t\t\t&quot;</span> <span class='plus op'>+</span> <span class='exon identifier id'>exon</span><span class='dot token'>.</span><span class='id identifier id'>id</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
      <span class='end end kw'>end</span>
    <span class='end end kw'>end</span>
  <span class='end end kw'>end</span>
</pre>
<p>
In addition to the methods which are present on every feature, the
transcript class has many other methods which are commonly used. Several
methods can be used to obtain transcript related sequences. At the time of
writing this tutorial, these methods return strings rather than bioruby
Bio::Sequence objects. The following example demonstrates the use of some
of these methods:
</p>
<ul>
<li>The Ensembl::Core::Transcript#seq method returns the concatenation of the
exon sequences. This is the cDNA of the transcript:

<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;cDNA: &quot;</span> <span class='plus op'>+</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='seq identifier id'>seq</span>
</pre>
</li>
<li>The Ensembl::Core::Transcript#cds_seq method returns only the CDS of the
transcript

<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;CDS: &quot;</span> <span class='plus op'>+</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='cds_seq identifier id'>cds_seq</span>
</pre>
</li>
<li>UTR sequences are obtained via the five_prime_utr_seq and
three_prime_utr_seq methods

<pre class="code">
  <span class='fiv_utr identifier id'>fiv_utr</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='five_prime_utr_seq identifier id'>five_prime_utr_seq</span>
  <span class='thr_utr identifier id'>thr_utr</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='three_prime_utr_seq identifier id'>three_prime_utr_seq</span>

  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;5' UTR: &quot;</span> <span class='plus op'>+</span> <span class='lparen token'>(</span> <span class='fiv_utr identifier id'>fiv_utr</span><span class='dot token'>.</span><span class='nil? fid id'>nil?</span> <span class='integer val'>? </span><span class='string val'>'None'</span> <span class='colon op'>:</span> <span class='fiv_utr identifier id'>fiv_utr</span> <span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;3' UTR: &quot;</span> <span class='plus op'>+</span> <span class='lparen token'>(</span> <span class='thr_utr identifier id'>thr_utr</span><span class='dot token'>.</span><span class='nil? fid id'>nil?</span> <span class='integer val'>? </span><span class='string val'>'None'</span> <span class='colon op'>:</span> <span class='thr_utr identifier id'>thr_utr</span> <span class='rparen token'>)</span>
</pre>
</li>
<li>The peptide sequence is obtained from the
Ensembl::Core::Transcript#protein_seq method. If the transcript is
non-coding, undef is returned.

<pre class="code">
  <span class='peptide identifier id'>peptide</span> <span class='assign token'>=</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='protein_seq identifier id'>protein_seq</span>

  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;Translation: &quot;</span> <span class='plus op'>+</span> <span class='lparen token'>(</span> <span class='peptide identifier id'>peptide</span><span class='dot token'>.</span><span class='nil? fid id'>nil?</span> <span class='integer val'>? </span><span class='string val'>'None'</span> <span class='colon op'>:</span> <span class='peptide identifier id'>peptide</span> <span class='rparen token'>)</span>
</pre>
</li>
</ul>
<h2>Translations and ProteinFeatures</h2>
<p>
Translation objects and peptide sequence can be extracted from a Transcript
object. It is important to remember that some Ensembl transcripts are
non-coding (pseudo-genes, ncRNAs, etc.) and have no translation. The
primary purpose of a Translation object is to define the CDS and UTRs of
its associated Transcript object. Peptide sequence is obtained directly
from a Transcript object not a Translation object as might be expected. The
following example obtains the peptide sequence of a
Ensembl::Core::Transcript and the Ensembl::Core::Translation&#8217;s stable
identifier:
</p>
<pre class="code">
  <span class='stable_id identifier id'>stable_id</span> <span class='assign token'>=</span> <span class='string val'>'ENST00000044768'</span>

  <span class='transcript identifier id'>transcript</span> <span class='assign token'>=</span> <span class='Transcript constant id'>Transcript</span><span class='dot token'>.</span><span class='find_by_stable_id identifier id'>find_by_stable_id</span><span class='lparen token'>(</span><span class='stable_id identifier id'>stable_id</span><span class='rparen token'>)</span>

  <span class='puts identifier id'>puts</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>
  <span class='puts identifier id'>puts</span> <span class='transcript identifier id'>transcript</span><span class='dot token'>.</span><span class='translation identifier id'>translation</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>
</pre>
<p>
&#8212; NOTE TO SELF: the following bit is not implemented yet&#8230;
</p>
<p>
ProteinFeatures are features which are on an amino acid sequence rather
than a nucleotide sequence. The method get_all_ProteinFeatures() can be
used to obtain a set of protein features from a Translation object.
</p>
<p>
$translation = $transcript-&gt;translation();
</p>
<p>
my @pfeatures = @{ $translation-&gt;get_all_ProteinFeatures() }; while ( my
$pfeature = shift @pfeatures ) {
</p>
<pre class="code">
    <span class='my identifier id'>my</span> <span class='$logic_name gvar id'>$logic_name</span> <span class='assign token'>=</span> <span class='$pfeature gvar id'>$pfeature</span><span class='minus op'>-</span><span class='gt op'>&gt;</span><span class='analysis identifier id'>analysis</span><span class='lparen token'>(</span><span class='rparen token'>)</span><span class='minus op'>-</span><span class='gt op'>&gt;</span><span class='logic_name identifier id'>logic_name</span><span class='lparen token'>(</span><span class='rparen token'>)</span><span class='semicolon token'>;</span>

    <span class='printf identifier id'>printf</span><span class='lparen token'>(</span>
        <span class='string val'>&quot;%d-%d %s %s %s\n&quot;</span><span class='comma token'>,</span>
        <span class='$pfeature gvar id'>$pfeature</span><span class='minus op'>-</span><span class='gt op'>&gt;</span><span class='start identifier id'>start</span><span class='lparen token'>(</span><span class='rparen token'>)</span><span class='comma token'>,</span> <span class='$pfeature gvar id'>$pfeature</span><span class='minus op'>-</span><span class='gt op'>&gt;</span><span class='end end kw'>end</span><span class='lparen token'>(</span><span class='rparen token'>)</span><span class='comma token'>,</span> <span class='$logic_name gvar id'>$logic_name</span><span class='comma token'>,</span>
        <span class='$pfeature gvar id'>$pfeature</span><span class='minus op'>-</span><span class='gt op'>&gt;</span><span class='interpro_ac identifier id'>interpro_ac</span><span class='lparen token'>(</span><span class='rparen token'>)</span><span class='comma token'>,</span>
        <span class='$pfeature gvar id'>$pfeature</span><span class='minus op'>-</span><span class='gt op'>&gt;</span><span class='idesc identifier id'>idesc</span><span class='lparen token'>(</span><span class='rparen token'>)</span>
    <span class='rparen token'>)</span><span class='semicolon token'>;</span>
</pre>
<p>
}
</p>
<p>
If only the protein features created by a particular analysis are desired
the name of the analysis can be provided as an argument. To obtain the
subset of features which are considered to be &#8216;domain&#8217; features
the convenience method get_all_DomainFeatures() can be used:
</p>
<p>
my $seg_features =
$translation-&gt;get_all_ProteinFeatures(&#8216;Seg&#8217;); my
$domain_features = $translation-&gt;get_all_DomainFeatures(); ++
</p>
<h2>PredictionTranscripts</h2>
<p>
PredictionTranscripts are the results of ab initio gene finding programs
that are stored in Ensembl. Example programs include Genscan and SNAP.
Prediction transcripts have the same interface as normal transcripts and
thus they can be used in the same way.
</p>
<pre class="code">
  <span class='prediction_transcripts identifier id'>prediction_transcripts</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='prediction_transcripts identifier id'>prediction_transcripts</span>
  <span class='prediction_transcripts identifier id'>prediction_transcripts</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='pt identifier id'>pt</span><span class='bitor op'>|</span>
    <span class='exons identifier id'>exons</span> <span class='assign token'>=</span> <span class='pt identifier id'>pt</span><span class='dot token'>.</span><span class='prediction_exons identifier id'>prediction_exons</span>
    <span class='type identifier id'>type</span> <span class='assign token'>=</span> <span class='pt identifier id'>pt</span><span class='dot token'>.</span><span class='analysis identifier id'>analysis</span><span class='dot token'>.</span><span class='logic_name identifier id'>logic_name</span>

    <span class='puts identifier id'>puts</span> <span class='dstring node'>&quot;#{type} prediction has #{exons.length.to_s} exons&quot;</span>

    <span class='exons identifier id'>exons</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='exon identifier id'>exon</span><span class='bitor op'>|</span>
      <span class='puts identifier id'>puts</span> <span class='exon identifier id'>exon</span><span class='dot token'>.</span><span class='to_yaml identifier id'>to_yaml</span>
    <span class='end end kw'>end</span>
  <span class='end end kw'>end</span>
</pre>
<h2>Alignment Features</h2>
<p>
Two types of alignments are stored in the core Ensembl database: alignments
of DNA sequence to the genome and alignments of peptide sequence to the
genome. These can be retrieved as Ensembl::Core::DnaAlignFeatures and
Ensembl::Core::ProteinAlignFeatures respectively. A single gapped alignment
is represented by a single feature with a cigar line. A cigar line is a
compact representation of a gapped alignment as single string containing
letters M (match) D (deletion), and I (insertion) prefixed by integer
lengths (the number may be omitted if it is 1). &#8212; NOTE TO SELF: not
implemented yet A gapped alignment feature can be broken into its component
ungapped alignments by the method ungapped_features() which returns a list
of FeaturePair objects. ++ The following example shows the retrieval of
some alignment features.
</p>
<ul>
<li>Retrieve dna-dna alignment features from the slice region

<pre class="code">
  <span class='features identifier id'>features</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='dna_align_features identifier id'>dna_align_features</span><span class='lparen token'>(</span><span class='string val'>'Vertrna'</span><span class='rparen token'>)</span>
  <span class='features identifier id'>features</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='f identifier id'>f</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='f identifier id'>f</span><span class='dot token'>.</span><span class='to_yaml identifier id'>to_yaml</span>
  <span class='end end kw'>end</span>
</pre>
</li>
<li>Retrieve protein-dna alignment features from the slice region

<pre class="code">
  <span class='features identifier id'>features</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='protein_align_features identifier id'>protein_align_features</span><span class='lparen token'>(</span><span class='string val'>'Swall'</span><span class='rparen token'>)</span>
  <span class='features identifier id'>features</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='f identifier id'>f</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='f identifier id'>f</span><span class='dot token'>.</span><span class='to_yaml identifier id'>to_yaml</span>
  <span class='end end kw'>end</span>
</pre>
</li>
</ul>
<h2>Repeats</h2>
<p>
Repetitive regions found by RepeatMasker and TRF (Tandem Repeat Finder) are
represented in the Ensembl database as RepeatFeatures. Short non-repetitive
regions between repeats are found by the program Dust and are also stored
as RepeatFeatures. RepeatFeatures can be retrieved and used in the same way
as other Ensembl features.
</p>
<pre class="code">
  <span class='repeats identifier id'>repeats</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='repeats identifier id'>repeats</span>
  <span class='repeats identifier id'>repeats</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='r identifier id'>r</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='r identifier id'>r</span><span class='dot token'>.</span><span class='display_id identifier id'>display_id</span> <span class='plus op'>+</span> <span class='string val'>&quot;\t&quot;</span> <span class='plus op'>+</span> <span class='repeat identifier id'>repeat</span><span class='dot token'>.</span><span class='start identifier id'>start</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span> <span class='plus op'>+</span> <span class='string val'>&quot;\t&quot;</span> <span class='plus op'>+</span> <span class='repeat identifier id'>repeat</span><span class='dot token'>.</span><span class='stop identifier id'>stop</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
  <span class='end end kw'>end</span>
</pre>
<p>
&#8212; NOTE TO SELF: not implemented yet RepeatFeatures are used to
perform repeat masking of the genomic sequence. Hard or soft-masked genomic
sequence can be retrieved from Slice objects using the
Slice#repeatmasked_seq method. Hard-masking replaces sequence in repeat
regions with Ns. Soft-masking replaces sequence in repeat regions with
lower-case sequence.
</p>
<pre class="code">
  <span class='unmasked_seq identifier id'>unmasked_seq</span>   <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='seq identifier id'>seq</span>
  <span class='hardmasked_seq identifier id'>hardmasked_seq</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='repeatmasked_seq identifier id'>repeatmasked_seq</span>
  <span class='softmasked_seq identifier id'>softmasked_seq</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='repeatmasked_seq identifier id'>repeatmasked_seq</span><span class='lparen token'>(</span><span class='undef undef kw'>undef</span><span class='comma token'>,</span> <span class='integer val'>1</span><span class='rparen token'>)</span>
</pre>
<ul>
<li>Soft-mask sequence using TRF results only

<p>
tandem_masked_seq = slice.repeatmasked_seq([&#8216;TRF&#8217;], 1)
</p>
</li>
</ul>
<p>
++
</p>
<h2>Markers</h2>
<p>
Markers are imported into the Ensembl database from UniSTS and several
other sources. A marker in Ensembl consists of a pair of primer sequences,
an expected product size and a set of associated identifiers known as
synonyms. Markers are placed on the genome electronically using an analysis
program such as ePCR and their genomic positions are retrievable as
MarkerFeatures. Map locations (genetic, radiation hybrid and in situ
hybridization) for markers obtained from actual experimental evidence are
also accessible.
</p>
<p>
Markers can be fetched by their name. The Marker#find_all_by_name returns
an array, and Marker#find_by_name returns the first element of that array,
i.e. a marker object.
</p>
<pre class="code">
  <span class='marker identifier id'>marker</span> <span class='assign token'>=</span> <span class='Marker constant id'>Marker</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'D9S1038E'</span><span class='rparen token'>)</span>
</pre>
<ul>
<li>Display the various names associated with the same marker

<pre class="code">
  <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='marker_synonyms identifier id'>marker_synonyms</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='ms identifier id'>ms</span><span class='bitor op'>|</span>
    <span class='if if kw'>if</span> <span class='ms identifier id'>ms</span><span class='dot token'>.</span><span class='source identifier id'>source</span><span class='dot token'>.</span><span class='nil? fid id'>nil?</span>
      <span class='puts identifier id'>puts</span> <span class='ms identifier id'>ms</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
    <span class='else else kw'>else</span>
      <span class='puts identifier id'>puts</span> <span class='ms identifier id'>ms</span><span class='dot token'>.</span><span class='source identifier id'>source</span> <span class='plus op'>+</span> <span class='string val'>':'</span> <span class='plus op'>+</span> <span class='ms identifier id'>ms</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
    <span class='end end kw'>end</span>
  <span class='end end kw'>end</span>
</pre>
</li>
<li>Display the primer info

<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;left primer: &quot;</span> <span class='plus op'>+</span> <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='left_primer identifier id'>left_primer</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;right primer: &quot;</span> <span class='plus op'>+</span> <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='right_primer identifier id'>right_primer</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;product size: &quot;</span> <span class='plus op'>+</span> <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='min_primer_dist identifier id'>min_primer_dist</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span> <span class='plus op'>+</span> <span class='string val'>'-'</span> <span class='plus op'>+</span> <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='max_primer_dist identifier id'>max_primer_dist</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
</pre>
</li>
<li>Display out genetic/RH/FISH map information

<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;Map locations:&quot;</span>
  <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='marker_map_locations identifier id'>marker_map_locations</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='mapping identifier id'>mapping</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='mapping identifier id'>mapping</span><span class='dot token'>.</span><span class='map identifier id'>map</span><span class='dot token'>.</span><span class='map_name identifier id'>map_name</span> <span class='plus op'>+</span> <span class='string val'>&quot;\t&quot;</span> <span class='plus op'>+</span> <span class='mapping identifier id'>mapping</span><span class='dot token'>.</span><span class='chromosome_name identifier id'>chromosome_name</span> <span class='plus op'>+</span> <span class='string val'>&quot;\t&quot;</span> <span class='plus op'>+</span> <span class='mapping identifier id'>mapping</span><span class='dot token'>.</span><span class='position identifier id'>position</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
  <span class='end end kw'>end</span>
</pre>
</li>
</ul>
<p>
MarkerFeatures, which represent genomic positions of markers, can be
retrieved and manipulated in the same way as other Ensembl features.
</p>
<ul>
<li>Obtain the positions for an already retrieved marker

<pre class="code">
  <span class='marker identifier id'>marker</span><span class='dot token'>.</span><span class='marker_features identifier id'>marker_features</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='mf identifier id'>mf</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='mf identifier id'>mf</span><span class='dot token'>.</span><span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='display_name identifier id'>display_name</span>
  <span class='end end kw'>end</span>
</pre>
</li>
<li>Retrieve all marker features in a given region

<pre class="code">
  <span class='marker_features identifier id'>marker_features</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='marker_features identifier id'>marker_features</span>
  <span class='marker_features identifier id'>marker_features</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='mf identifier id'>mf</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='mf identifier id'>mf</span><span class='dot token'>.</span><span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='display_name identifier id'>display_name</span>
  <span class='end end kw'>end</span>
</pre>
</li>
</ul>
<h2>MiscFeatures</h2>
<p>
MiscFeatures are features with arbitrary attributes which are placed into
arbitrary groupings. MiscFeatures can be retrieved as any other feature and
are classified into distinct sets by a set code. Generally it only makes
sense to retrieve all features which have a particular set code because
very diverse types of MiscFeatures are stored in the database.
</p>
<p>
MiscFeature attributes are represented by Attribute objects and can be
retrieved via a get_all_Attributes() method.
</p>
<p>
The following example retrieves all MiscFeatures representing ENCODE
regions on a given slice and prints out their attributes:
</p>
<pre class="code">
  <span class='encode_regions identifier id'>encode_regions</span> <span class='assign token'>=</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='misc_features identifier id'>misc_features</span><span class='lparen token'>(</span><span class='string val'>'encode'</span><span class='rparen token'>)</span>
  <span class='encode_regions identifier id'>encode_regions</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='er identifier id'>er</span><span class='bitor op'>|</span>
    <span class='attributes identifier id'>attributes</span> <span class='assign token'>=</span> <span class='er identifier id'>er</span><span class='dot token'>.</span><span class='misc_attribs identifier id'>misc_attribs</span>
    <span class='attributes identifier id'>attributes</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='a identifier id'>a</span><span class='bitor op'>|</span>
      <span class='puts identifier id'>puts</span> <span class='a identifier id'>a</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
    <span class='end end kw'>end</span>
  <span class='end end kw'>end</span>
</pre>
<p>
This example retrieves all misc features representing a BAC clone via its
name and prints out their location and other information:
</p>
<pre class="code">
  <span class='clones identifier id'>clones</span> <span class='assign token'>=</span> <span class='MiscFeature constant id'>MiscFeature</span><span class='dot token'>.</span><span class='find_all_by_attribute_type_value identifier id'>find_all_by_attribute_type_value</span><span class='lparen token'>(</span><span class='string val'>'name'</span><span class='comma token'>,</span> <span class='string val'>'RP11-62N12'</span><span class='rparen token'>)</span>
  <span class='clones identifier id'>clones</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='clone identifier id'>clone</span><span class='bitor op'>|</span>
    <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='clone identifier id'>clone</span><span class='dot token'>.</span><span class='slice identifier id'>slice</span>
    <span class='puts identifier id'>puts</span> <span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='to_yaml identifier id'>to_yaml</span>

    <span class='attributes identifier id'>attributes</span> <span class='assign token'>=</span> <span class='clone identifier id'>clone</span><span class='dot token'>.</span><span class='misc_attribs identifier id'>misc_attribs</span>
    <span class='attributes identifier id'>attributes</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='a identifier id'>a</span><span class='bitor op'>|</span>
      <span class='puts identifier id'>puts</span> <span class='a identifier id'>a</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
    <span class='end end kw'>end</span>
  <span class='end end kw'>end</span>
</pre>
<h2>External References</h2>
<p>
Ensembl cross references its genes, transcripts and translations with
identifiers from other databases. A cross reference is referenced by a Xref
object. The following code snippet retrieves and prints Xrefs for a gene,
its transcripts and its translations:
</p>
<ul>
<li>Get the &#8216;COG6&#8217; gene from human

<pre class="code">
  <span class='cog6 identifier id'>cog6</span> <span class='assign token'>=</span> <span class='Gene constant id'>Gene</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'COG6'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='string val'>'GENE: '</span> <span class='plus op'>+</span> <span class='cog6 identifier id'>cog6</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span> <span class='plus op'>+</span> <span class='string val'>&quot; (internal id: &quot;</span> <span class='plus op'>+</span> <span class='cog6 identifier id'>cog6</span><span class='dot token'>.</span><span class='id identifier id'>id</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span> <span class='plus op'>+</span> <span class='string val'>&quot;)&quot;</span>

  <span class='cog6 identifier id'>cog6</span><span class='dot token'>.</span><span class='xrefs identifier id'>xrefs</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='x identifier id'>x</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='x identifier id'>x</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
  <span class='end end kw'>end</span>

  <span class='cog6 identifier id'>cog6</span><span class='dot token'>.</span><span class='transcripts identifier id'>transcripts</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='t identifier id'>t</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='string val'>'TRANSCRIPT: '</span> <span class='plus op'>+</span> <span class='t identifier id'>t</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>
    <span class='t identifier id'>t</span><span class='dot token'>.</span><span class='xrefs identifier id'>xrefs</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='x identifier id'>x</span><span class='bitor op'>|</span>
      <span class='puts identifier id'>puts</span> <span class='string val'>&quot;\s\s&quot;</span> <span class='plus op'>+</span> <span class='x identifier id'>x</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
    <span class='end end kw'>end</span>

    <span class='comment val'># Watch out: pseudogenes have no translation</span>
    <span class='if if kw'>if</span> <span class='notop op'>!</span> <span class='t identifier id'>t</span><span class='dot token'>.</span><span class='translation identifier id'>translation</span><span class='dot token'>.</span><span class='nil? fid id'>nil?</span>
      <span class='translation identifier id'>translation</span> <span class='assign token'>=</span> <span class='t identifier id'>t</span><span class='dot token'>.</span><span class='translation identifier id'>translation</span>
      <span class='puts identifier id'>puts</span> <span class='string val'>&quot;\tTRANSLATION: &quot;</span> <span class='plus op'>+</span> <span class='translation identifier id'>translation</span><span class='dot token'>.</span><span class='stable_id identifier id'>stable_id</span>
      <span class='translation identifier id'>translation</span><span class='dot token'>.</span><span class='xrefs identifier id'>xrefs</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='x identifier id'>x</span><span class='bitor op'>|</span>
        <span class='puts identifier id'>puts</span> <span class='string val'>&quot;\t\s\s&quot;</span> <span class='plus op'>+</span> <span class='x identifier id'>x</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
      <span class='end end kw'>end</span>
    <span class='end end kw'>end</span>
  <span class='end end kw'>end</span>
</pre>
</li>
</ul>
<p>
Often it is useful to obtain all of the Xrefs associated with a gene and
its associated transcripts and translation as in the above example. As a
shortcut to calling #xrefs on all of the above objects the Gene#all_xrefs
method can be used instead. The above example could be shortened by using
the following:
</p>
<pre class="code">
  <span class='cog6 identifier id'>cog6</span><span class='dot token'>.</span><span class='all_xrefs identifier id'>all_xrefs</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='x identifier id'>x</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='x identifier id'>x</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span>
  <span class='end end kw'>end</span>
</pre>
<p>
This returns all xrefs for the gene itself, including those for all
transcripts and translations.
</p>
<h2>Coordinates</h2>
<p>
We have already discussed the fact that slices and features have
coordinates, but we have not defined exactly what these coordinates mean.
</p>
<p>
Ensembl, and many other bioinformatics applications, use inclusive
coordinates which start at 1. The first nucleotide of a DNA sequence is 1
and the first amino acid of a peptide sequence is also 1. The length of a
sequence is defined as end - start + 1.
</p>
<p>
In some rare cases inserts are specified with a start which is one greater
than the end. For example a feature with a start of 10 and an end of 9
would be a zero length feature between base pairs 9 and 10.
</p>
<p>
Slice coordinates are relative to the start of the underlying DNA sequence
region (a Ensembl::Core::SeqRegion object). The strand of the slice
represents its orientation relative to the default orientation of the
sequence region. By convention the start of the slice is always less than
the end, and does not vary with its strandedness. Most slices you will
encounter will have a strand of 1, and this is what we will consider in our
examples. It is legal to create a slice which extends past the boundaries
of a sequence region.
</p>
<h2>Coordinate Systems, Sequence Regions and Slices</h2>
<p>
Sequences stored in Ensembl are associated with coordinate systems. What
the coordinate systems are varies from species to species. For example, the
homo_sapiens database has the following coordinate systems: contig, clone,
supercontig, chromosome. Sequence and features may be retrieved from any
coordinate system despite the fact they are only stored internally in a
single coordinate system. The database stores the relationship between
these coordinate systems and the API provides means to convert between
them. The API has a Ensembl::Core::CoordSystem object and object adaptor,
however, these are most often used internally. The following example
fetches a chromosome coordinate system object from the database:
</p>
<pre class="code">
  <span class='chr_coord_system identifier id'>chr_coord_system</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='string val'>&quot;Coordinate system: &quot;</span> <span class='plus op'>+</span> <span class='chr_coord_system identifier id'>chr_coord_system</span><span class='dot token'>.</span><span class='name identifier id'>name</span> <span class='plus op'>+</span> <span class='string val'>&quot;:&quot;</span> <span class='plus op'>+</span> <span class='chr_coord_system identifier id'>chr_coord_system</span><span class='dot token'>.</span><span class='version identifier id'>version</span>
</pre>
<p>
A coordinate system is uniquely defined by its name and version. Most
coordinate systems do not have a version, and the ones that do have a
default version, so it is usually sufficient to use only the name when
requesting a coordinate system. For example, chromosome coordinate systems
have a version which is the assembly that defined the construction of the
coordinate system. The version of the human chromosome coordinate system
might be something like NCBI35 or NCBI36, depending on the version of the
Core databases used.
</p>
<p>
Ensembl::Core::SeqRegion objects have an associated
Ensembl::Core::CoordSystem object and a #name method that returns its name
which uniquely defines them. You may have noticed that the coordinate
system of the sequence region was specified when obtaining a slice in the
#fetch_by_region method. Similarly the version may also be specified
(though it can almost always be omitted):
</p>
<pre class="code">
  <span class='slice identifier id'>slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span> <span class='string val'>'X'</span><span class='comma token'>,</span> <span class='integer val'>1000000</span><span class='comma token'>,</span> <span class='integer val'>10000000</span><span class='comma token'>,</span> <span class='string val'>'NCBI36'</span><span class='rparen token'>)</span>
</pre>
<p>
To obtain all sequence regions for a given coordinate system, just call the
Ensembl::Core::CoordSystem#seq_regions method.
</p>
<pre class="code">
  <span class='coord_system identifier id'>coord_system</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find_by_name identifier id'>find_by_name</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='rparen token'>)</span>
  <span class='chromomsomes identifier id'>chromomsomes</span> <span class='assign token'>=</span> <span class='coord_system identifier id'>coord_system</span><span class='dot token'>.</span><span class='seq_regions identifier id'>seq_regions</span>
  <span class='chromosomes identifier id'>chromosomes</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='chr identifier id'>chr</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='chr identifier id'>chr</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
  <span class='end end kw'>end</span>
</pre>
<p>
Sometimes it is useful to obtain full slices of every sequence region in a
given coordinate system; this may be done using the Slice#fetch_all method:
</p>
<pre class="code">
  <span class='chromosomes identifier id'>chromosomes</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_all identifier id'>fetch_all</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='rparen token'>)</span>
  <span class='clones identifier id'>clones</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_all identifier id'>fetch_all</span><span class='lparen token'>(</span><span class='string val'>'clone'</span><span class='rparen token'>)</span>
</pre>
<p>
Now suppose that you wish to write code which is independent of the species
used. Not all species have the same coordinate systems; the available
coordinate systems depends on the style of assembly used for that species
(WGS, clone-based, etc.). You can obtain the list of available coordinate
systems for a species using the Ensembl::Core::CoordSystem#find(:all)
method and there is also a special pseudo-coordinate system named toplevel.
The toplevel coordinate system is not a real coordinate system, but is used
to refer to the highest level coordinate system in a given region. The
toplevel coordinate system is particularly useful in genomes that are
incompletely assembled. For example, the latest zebrafish genome consists
of a set of assembled chromosomes, and a set of supercontigs that are not
part of any chromosome. In this example, the toplevel coordinate system
sometimes refers to the chromosome coordinate system and sometimes to the
supercontig coordinate system depending on the region it is used in.
</p>
<ul>
<li>List all coordinate systems in this database:

<pre class="code">
  <span class='coord_systems identifier id'>coord_systems</span> <span class='assign token'>=</span> <span class='CoordSystem constant id'>CoordSystem</span><span class='dot token'>.</span><span class='find identifier id'>find</span><span class='lparen token'>(</span><span class='symbol val'>:all</span><span class='rparen token'>)</span>
  <span class='coord_systems identifier id'>coord_systems</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='coord_system identifier id'>coord_system</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='coord_system identifier id'>coord_system</span><span class='dot token'>.</span><span class='name identifier id'>name</span> <span class='plus op'>+</span> <span class='string val'>&quot;\t&quot;</span> <span class='plus op'>+</span> <span class='coord_system identifier id'>coord_system</span><span class='dot token'>.</span><span class='version identifier id'>version</span>
  <span class='end end kw'>end</span>
</pre>
</li>
<li>Get all slices on the highest coordinate system:

<pre class="code">
  <span class='slices identifier id'>slices</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_all identifier id'>fetch_all</span><span class='lparen token'>(</span><span class='string val'>'top_level'</span><span class='rparen token'>)</span>
</pre>
</li>
</ul>
<h2>Transform</h2>
<p>
Features on a seq_region in a given coordinate system may be moved to
another coordinate system. This is useful if you are working with a
particular coordinate system but you are interested in obtaining the
features coordinates in another coordinate system.
</p>
<p>
TheEnsembl::Core::Sliceable#transform method (available to all features)
can be used to move a feature to any coordinate system which is in the
database. The feature will be a clone of the original feature, but with a
different seq_region associated with it, as well as seq_region_start,
seq_region_end and seq_region_strand.
</p>
<pre class="code">
  <span class='comment val'>#Suppose original_feature is on the 'chromosome' coordinate system</span>
  <span class='new_feature identifier id'>new_feature</span> <span class='assign token'>=</span> <span class='original_feature identifier id'>original_feature</span><span class='dot token'>.</span><span class='transform identifier id'>transform</span><span class='lparen token'>(</span><span class='string val'>'clone'</span><span class='rparen token'>)</span>
  <span class='if if kw'>if</span> <span class='new_feature identifier id'>new_feature</span><span class='dot token'>.</span><span class='nil? fid id'>nil?</span>
    <span class='puts identifier id'>puts</span> <span class='string val'>&quot;Feature is not defined in clonal coordinate system&quot;</span>
  <span class='else else kw'>else</span>
    <span class='puts identifier id'>puts</span> <span class='string val'>&quot;Feature's clonal position:&quot;</span>
    <span class='puts identifier id'>puts</span> <span class='new_feature identifier id'>new_feature</span><span class='dot token'>.</span><span class='seq_region identifier id'>seq_region</span><span class='dot token'>.</span><span class='name identifier id'>name</span>
    <span class='puts identifier id'>puts</span> <span class='new_feature identifier id'>new_feature</span><span class='dot token'>.</span><span class='seq_region_start identifier id'>seq_region_start</span><span class='dot token'>.</span><span class='to_s identifier id'>to_s</span> <span class='plus op'>+</span> <span class='string val'>&quot;..&quot;</span> <span class='plus op'>+</span> <span class='new_feature_seq_region_end identifier id'>new_feature_seq_region_end</span>
  <span class='end end kw'>end</span>
</pre>
<p>
To print out the position of a feature (i.e. concatenating the seq_region
name, start, end), it&#8217;s easier to create a slice of it first, and
then calling the Ensembl::Core::Slice#display_name method:
</p>
<pre class="code">
  <span class='puts identifier id'>puts</span> <span class='new_feature identifier id'>new_feature</span><span class='dot token'>.</span><span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='display_name identifier id'>display_name</span>
</pre>
<p>
The transform method returns a copy of the original feature in the new
coordinate system, or nil if the feature is not defined in that coordinate
system. A feature is considered to be undefined in a coordinate system if
it overlaps an undefined region or if it crosses a coordinate system
boundary. Take for example the tiling path relationship between chromosome
and contig coordinate systems:
</p>
<pre class="code">
                    <span class='bitor op'>|</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitor op'>|</span> <span class='lparen token'>(</span><span class='Feature constant id'>Feature</span> <span class='A constant id'>A</span><span class='rparen token'>)</span> <span class='bitor op'>|</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitnot op'>~</span><span class='bitor op'>|</span> <span class='lparen token'>(</span><span class='Feature constant id'>Feature</span> <span class='B constant id'>B</span><span class='rparen token'>)</span>

  <span class='lparen token'>(</span><span class='ctg identifier id'>ctg</span> <span class='integer val'>1</span><span class='rparen token'>)</span> <span class='lbrack token'>[</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='assign token'>=</span><span class='rbrack token'>]</span>
          <span class='lparen token'>(</span><span class='ctg identifier id'>ctg</span> <span class='integer val'>2</span><span class='rparen token'>)</span> <span class='lparen token'>(</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='minus op'>-</span><span class='opasgn op'>-=</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='rbrack token'>]</span> <span class='lparen token'>(</span><span class='ctg identifier id'>ctg</span> <span class='integer val'>2</span><span class='rparen token'>)</span>
                        <span class='lparen token'>(</span><span class='ctg identifier id'>ctg</span> <span class='integer val'>3</span><span class='rparen token'>)</span>   <span class='lparen token'>(</span><span class='minus op'>-</span><span class='opasgn op'>-=</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='eqq op'>===</span><span class='eq op'>==</span><span class='rbrack token'>]</span> <span class='lparen token'>(</span><span class='ctg3 identifier id'>ctg3</span><span class='rparen token'>)</span>
</pre>
<p>
Both Feature A and Feature B are defined in the chromosomal coordinate
system described by the tiling path of contigs. However, Feature A is not
defined in the contig coordinate system because it spans both Contig 1 and
Contig 2. Feature B, on the other hand, is still defined in the contig
coordinate system.
</p>
<p>
The special toplevel coordinate system can also be used in this instance to
move the feature to the highest possible coordinate system in a given
region:
</p>
<pre class="code">
  <span class='new_feature identifier id'>new_feature</span> <span class='assign token'>=</span> <span class='original_feature identifier id'>original_feature</span><span class='dot token'>.</span><span class='transform identifier id'>transform</span><span class='lparen token'>(</span><span class='string val'>'toplevel'</span><span class='rparen token'>)</span>
  <span class='puts identifier id'>puts</span> <span class='new_feature identifier id'>new_feature</span><span class='dot token'>.</span><span class='slice identifier id'>slice</span><span class='dot token'>.</span><span class='display_name identifier id'>display_name</span>
</pre>
<p>
<b>NOTE</b>: In contrast to the perl API, there is no #transfer method.
</p>
<h2>Project</h2>
<p>
When moving features between coordinate systems it is usually sufficient to
use the Ensembl::Core::Sliceable#transform method. Sometimes, however, it
is necessary to obtain coordinates in a another coordinate system even when
a coordinate system boundary is crossed. Even though the feature is
considered to be undefined in this case, the feature&#8217;s coordinates
can still be obtained in the requested coordinate system using the
Slice#project method.
</p>
<p>
While #transform is a method only available to features, both slices and
features have their own #project methods, which take the same arguments and
have the same return values. The #project method takes a coordinate system
name as an argument and returns an array of Slice and Gap objects. The
following example illustrates the use of the #project method on a slice.
The #project method on a feature can be used in the same way. As with the
feature #transform method the pseudo coordinate system toplevel can be used
to indicate you wish to project to the highest possible level.
</p>
<pre class="code">
  <span class='original_slice identifier id'>original_slice</span> <span class='assign token'>=</span> <span class='Slice constant id'>Slice</span><span class='dot token'>.</span><span class='fetch_by_region identifier id'>fetch_by_region</span><span class='lparen token'>(</span><span class='string val'>'chromosome'</span><span class='comma token'>,</span> <span class='string val'>'4'</span><span class='comma token'>,</span> <span class='integer val'>329500</span><span class='comma token'>,</span> <span class='integer val'>380000</span><span class='rparen token'>)</span>
  <span class='target_slices identifier id'>target_slices</span> <span class='assign token'>=</span> <span class='@source_slice_contigs_with_strand ivar id'>@source_slice_contigs_with_strand</span><span class='dot token'>.</span><span class='project identifier id'>project</span><span class='lparen token'>(</span><span class='string val'>'contig'</span><span class='rparen token'>)</span>
  <span class='target_slices identifier id'>target_slices</span><span class='dot token'>.</span><span class='each identifier id'>each</span> <span class='do do kw'>do</span> <span class='bitor op'>|</span><span class='ts identifier id'>ts</span><span class='bitor op'>|</span>
    <span class='puts identifier id'>puts</span> <span class='ts identifier id'>ts</span><span class='dot token'>.</span><span class='display_name identifier id'>display_name</span>
  <span class='end end kw'>end</span>
</pre>
<p>
The above returns (for Bos taurus):
</p>
<pre class="code">
  <span class='contig identifier id'>contig</span><span class='colon2 op'>::</span><span class='AAFC03092598 constant id'>AAFC03092598</span><span class='symbol val'>:60948</span><span class='symbol val'>:61145</span><span class='symbol val'>:1</span>
  <span class='contig identifier id'>contig</span><span class='colon2 op'>::</span><span class='AAFC03118261 constant id'>AAFC03118261</span><span class='symbol val'>:25411</span><span class='symbol val'>:37082</span><span class='symbol val'>:1</span>
  <span class='contig identifier id'>contig</span><span class='colon2 op'>::</span><span class='AAFC03092594 constant id'>AAFC03092594</span><span class='symbol val'>:1</span><span class='symbol val'>:3622</span><span class='symbol val'>:-1</span>
  <span class='contig identifier id'>contig</span><span class='symbol val'>:gap</span><span class='symbol val'>:50</span>
  <span class='contig identifier id'>contig</span><span class='colon2 op'>::</span><span class='AAFC03092597 constant id'>AAFC03092597</span><span class='symbol val'>:820</span><span class='symbol val'>:35709</span><span class='symbol val'>:-1</span>
  <span class='contig identifier id'>contig</span><span class='colon2 op'>::</span><span class='AAFC03032210 constant id'>AAFC03032210</span><span class='symbol val'>:13347</span><span class='symbol val'>:13415</span><span class='symbol val'>:1</span>
</pre>
</div></div>
    
    <div id="footer">
  Generated on Wed Dec 15 19:18:12 2010 by 
  <a href="http://yardoc.org" title="Yay! A Ruby Documentation Tool" target="_parent">yard</a>
  0.6.3 (ruby-1.8.7).
</div>

  </body>
</html>